Enable running the VS Code extension host on the workspace (Node.js) by default by joao-boechat · Pull Request #3093 · microsoft/qdk

joao-boechat · 2026-04-03T20:01:31Z

Summary

This PR makes the Q# VS Code extension run its extension host primarily on the workspace side (Node.js) rather than on the UI side (browser). This is important for remote development scenarios — WSL, SSH, Codespaces, Dev Containers — where keeping the extension host close to the workspace avoids bugs and simplifies the architecture. The extension still supports running on the UI side for VS Code for Web.

To make this work, the Node.js entry point of the qsharp-lang npm package needed to function correctly. Rather than fixing the separate Node.js codepath, we unified both entry points into a single platform-agnostic module, using the web-worker package to abstract away Worker API differences between browsers and Node.js.

Motivation

The Q# extension was originally built as a web-first extension, meaning the extension host always ran on the UI side (browser), even in desktop VS Code. This caused issues in remote development scenarios (WSL, SSH, Codespaces, Dev Containers) where the extension host needs to run close to the workspace for correct behavior. By making the Node.js entry point the default, the extension host runs on the workspace side, avoiding these issues.

Additionally, the npm package previously maintained two parallel codepaths — browser.ts and main.ts — each with its own wasm loading strategy, worker proxy implementation, and per-service worker scripts. The build system also produced two separate wasm-bindgen targets (web and nodejs) and used npm conditional exports to route consumers to the right entry point. The Node.js path was incomplete and buggy, and the duplication made changes error-prone. Unifying these into a single platform-agnostic entry point simplifies the codebase and eliminates this class of bugs.

Architecture (of qsharp-lang)

Before

graph TD
    subgraph "npm package entry points"
        B["browser.ts (browser entry)"]
        M["main.ts (Node.js entry)"]
    end

    B --> WB["workers/browser.ts"]
    M --> WN["workers/node.ts"]

    WB --> CWB["compiler/worker-browser.ts"]
    WB --> LSWB["language-service/worker-browser.ts"]
    WB --> DSWB["debug-service/worker-browser.ts"]

    WN --> CWN["compiler/worker-node.ts"]
    WN --> LSWN["language-service/worker-node.ts"]
    WN --> DSWN["debug-service/worker-node.ts"]

    CWB --> WASMW["lib/web/qsc_wasm.js"]
    CWN --> WASMN["lib/nodejs/qsc_wasm.cjs"]

After

graph TD
    subgraph "npm package entry point"
        M["main.ts (single entry)"]
    end

    M --> WM["workers/main.ts (proxy, uses web-worker pkg)"]

    WW["workers/worker.ts (runs inside worker)"]

    WW --> CW["compiler/worker.ts"]
    WW --> LSW["language-service/worker.ts"]
    WW --> DSW["debug-service/worker.ts"]

    CW --> WASM["lib/web/qsc_wasm.js"]
    LSW --> WASM
    DSW --> WASM

    WM -.->|spawns| CW
    WM -.->|spawns| LSW
    WM -.->|spawns| DSW

Changes

`qsharp-lang` npm package (`source/npm/qsharp/`)

Deleted browser.ts and merged all functionality into main.ts — a single platform-agnostic entry point.
Consolidated per-service worker pairs (worker-browser.ts / worker-node.ts) into a single worker.ts each.
Replaced workers/browser.ts and workers/node.ts with workers/worker.ts (worker-side) and workers/main.ts (main-thread proxy using the web-worker package).
Added common-exports.ts for shared re-exports.
Only the web wasm-bindgen target is used; the nodejs target is no longer needed.
Simplified package.json exports — removed conditional browser/node/default routing.
Added web-worker (^1.5.0) as a dependency.
Some APIs are now async (getCompiler(), getDebugService(), getLanguageService(), getProjectLoader()), and worker factory functions now require an explicit worker path argument.

VS Code extension (`source/vscode/`)

Introduced a __PLATFORM__ build-time constant ("browser" or "node") to resolve the correct worker script paths at runtime.
The extension builds two platform bundles — one for browser and one for Node.js — each covering the extension host entry point (extension.ts) and the worker entry points (compilerWorker.ts, debug-service-worker.ts).
A single wasm file is now shared across both platforms (copied to wasm/), which is the main reason the overall VSIX size only grew from 3.9 MB to 4.09 MB despite adding a full Node.js bundle.
The web-worker package must be marked as an external dependency in the Node.js esbuild bundle. This is because web-worker performs an internal runtime check that breaks if its code is inlined into the bundle. As a result, it is copied into the extension's node_modules/ so it can be resolved at runtime (e.g. when installed from a VSIX).
Desktop entry point changed to ./out/node/extension.js.
Logs Platform, UI Kind, and Remote name during activation for diagnostics.

Build system (`build.py`)

Only the web wasm-bindgen target is built. Removed the nodejs target and its .js → .cjs renaming logic.

Tests (`source/npm/qsharp/test/`)

Updated to use the unified API (loadWasmModule, async service getters, explicit worker paths).

Extra

Fixes issue 2966

…browser vs node)

…environment

build.py

ScottCarda-MS · 2026-04-08T20:05:53Z

Since web workers was touched, I just wanted to double-check that the worker logic responsible for state-viz calculation on the circuit editor was still functional. I tested it and it seems to be working fine, but is there any reason to be concerned about that?

joao-boechat · 2026-04-08T21:08:11Z

@ScottCarda-MS I don't see any of the worker code I touched being referenced there. I think that the worker code in state-viz is named that way because it is supposed to be agnostic (browser and worker), so it avoids using API that's only available in browser. But my modifications shouldn't affect that part!

minestarks · 2026-04-09T18:24:10Z

source/npm/qsharp/src/common-exports.ts

Can these just live in main.ts ? I don't see a clear logical separation of what's reexported in main.ts vs what's reexported here, so I'm not sure if the separate file is necessary.

you're right, I did this when we still had two entrypoints and it still made sense. Will add it back to main

minestarks · 2026-04-09T18:34:07Z

source/vscode/src/extension.ts

    initOutputWindowLogger();
  }

+  log.info(`Platform: ${getPlatformEnv()}`);


Can we use log.debug or lower for this? info is enabled by default, and can get kind of noisy.

(These logs are pretty useful for testing this PR. Maybe you could clean up the logs just before merging.)

minestarks · 2026-04-09T19:39:41Z

source/vscode/src/common.ts

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
+declare const __PLATFORM__: string;


To make this less error prone you may want to strictly type it like this since we hardcode the values anyway.

Suggested change

declare const __PLATFORM__: string;

declare const __PLATFORM__: "browser" | "node";

Copilot

Pull request overview

This PR switches the Q# VS Code extension to run its extension host primarily on the workspace side (Node.js) by default (while still supporting VS Code for Web), and refactors the qsharp-lang npm package to use a single, platform-agnostic entry point with a unified worker strategy.

Changes:

Build and package the VS Code extension as separate browser and node bundles (plus node worker bundles), routing worker script paths via a __PLATFORM__ build-time constant.
Unify qsharp-lang’s browser/node entry points into main.ts, remove the separate Node.js wasm-bindgen target, and use web-worker to abstract Worker differences.
Update npm tests and tooling to use the unified async APIs and explicit worker paths.

Reviewed changes

Copilot reviewed 36 out of 37 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
source/vscode/src/webviewPanel.ts	Uses platform-specific output path for compiler worker script.
source/vscode/src/telemetry.ts	Adds platform-aware user agent / “browser release” reporting for Node vs browser.
source/vscode/src/qirGeneration.ts	Uses platform-specific output path for compiler worker script.
source/vscode/src/extension.ts	Logs platform/UI kind/remote name during activation for diagnostics.
source/vscode/src/documentation.ts	Uses platform-specific output path for compiler worker script.
source/vscode/src/debugger/debug-service-worker.ts	Simplifies worker entry to side-effect import of qsharp-lang worker module.
source/vscode/src/debugger/activate.ts	Uses platform-specific output path for debug worker script.
source/vscode/src/compilerWorker.ts	Simplifies worker entry to side-effect import of qsharp-lang worker module.
source/vscode/src/common.ts	Introduces `__PLATFORM__` and `getPlatformEnv()` for consistent path selection.
source/vscode/src/circuit.ts	Uses platform-specific output path for compiler worker script.
source/vscode/package.json	Sets desktop `main` to node bundle, web `browser` to browser bundle; adds `extensionKind`.
source/vscode/build.mjs	Builds browser/node/node-worker bundles; copies wasm and external node deps (web-worker).
source/npm/qsharp/test/languageService.js	Updates tests to preload wasm and await async service getters.
source/npm/qsharp/test/diagnostics.js	Updates tests for async compiler/loader getters and explicit worker paths.
source/npm/qsharp/test/circuits.js	Updates tests to preload wasm and await async compiler getter.
source/npm/qsharp/test/basics.js	Updates tests for async APIs and explicit worker paths for worker-based services.
source/npm/qsharp/src/workers/worker.ts	Keeps worker-side service initialization; removes proxy-creation from this module.
source/npm/qsharp/src/workers/node.ts	Removes legacy node-specific worker/proxy implementation.
source/npm/qsharp/src/workers/main.ts	Adds unified proxy creation using `web-worker` for both Node and browser.
source/npm/qsharp/src/main.ts	Unifies browser/node entrypoint; adds wasm loading/instantiation flow and async APIs.
source/npm/qsharp/src/log.ts	Updates description to reflect shared browser/Node logging infrastructure.
source/npm/qsharp/src/language-service/worker.ts	Switches to unified worker creation module; adds implicit message listener.
source/npm/qsharp/src/language-service/worker-node.ts	Removes legacy node worker entrypoint.
source/npm/qsharp/src/language-service/language-service.ts	Updates types/imports to align with unified entrypoint structure.
source/npm/qsharp/src/debug-service/worker.ts	Switches to unified worker creation module; adds implicit message listener.
source/npm/qsharp/src/debug-service/worker-node.ts	Removes legacy node worker entrypoint.
source/npm/qsharp/src/debug-service/debug-service.ts	Updates types/imports to align with unified entrypoint structure.
source/npm/qsharp/src/compiler/worker.ts	Switches to unified worker creation module; adds implicit message listener.
source/npm/qsharp/src/compiler/worker-node.ts	Removes legacy node worker entrypoint.
source/npm/qsharp/src/compiler/compiler.ts	Removes outdated comment about node-specific wasm types.
source/npm/qsharp/src/common-exports.ts	Adds shared re-export surface for unified entrypoint.
source/npm/qsharp/src/browser.ts	Removes legacy browser-only entrypoint.
source/npm/qsharp/README.md	Updates docs to describe single entry point and bundling expectations.
source/npm/qsharp/package.json	Simplifies exports to a single entry point; adds `web-worker` dependency.
source/npm/qsharp/generate_docs.js	Updates docs generation to initialize via web wasm glue.
package-lock.json	Adds `web-worker` dependency lock entries.
build.py	Removes nodejs wasm-bindgen target; builds/copies only web target artifacts.

Comments suppressed due to low confidence (3)

source/npm/qsharp/src/compiler/worker.ts:9

messageHandler is exported for backwards compatibility, but this module also unconditionally registers it via addEventListener. Any existing consumers that still do self.onmessage = messageHandler will now process each message twice (confirmed in source/playground/src/compiler-worker.ts). Consider removing the implicit registration, or making registration idempotent / updating consumers so only one handler is attached.
source/npm/qsharp/src/language-service/worker.ts:9
Same issue as the compiler worker: exporting messageHandler while also registering it with addEventListener can lead to double-handling when older consumers assign self.onmessage = messageHandler (confirmed in source/playground/src/language-service-worker.ts). Prefer a single registration mechanism to preserve backwards compatibility.
source/npm/qsharp/src/debug-service/worker.ts:9
messageHandler is exported for backwards compatibility, but this module also unconditionally registers it with addEventListener, which can lead to double-handling if any consumer also assigns self.onmessage = messageHandler. If backwards compatibility is required, prefer a single/explicit registration path or make registration idempotent.

Copilot · 2026-04-09T20:01:31Z

source/npm/qsharp/src/main.ts

+export function loadWasmModule(
+  uriOrBuffer: string | ArrayBuffer,
+): Promise<void> {


loadWasmModule is typed as accepting only string | ArrayBuffer, but callers in this repo pass a Uint8Array (e.g. vscode.workspace.fs.readFile(...)). The implementation works with any BufferSource, so the public type should be widened (e.g. string | BufferSource) to avoid TypeScript errors for valid usage.

Copilot · 2026-04-09T20:01:31Z

source/npm/qsharp/src/main.ts

+    const wasmRequst = await fetch(uriOrBuffer);
+    const wasmBuffer = await wasmRequst.arrayBuffer();


Minor typo: local variable wasmRequst looks like it should be wasmRequest for readability/searchability.

Suggested change

const wasmRequst = await fetch(uriOrBuffer);

const wasmBuffer = await wasmRequst.arrayBuffer();

const wasmRequest = await fetch(uriOrBuffer);

const wasmBuffer = await wasmRequest.arrayBuffer();

Copilot · 2026-04-09T20:01:31Z

source/vscode/build.mjs

+  const ctx = await context({
+    ...commonBuildOptions,
+    entryPoints: [
+      join(thisDir, "src", "extension.ts"),
+      join(thisDir, "src", "compilerWorker.ts"),
+      join(thisDir, "src", "debugger/debug-service-worker.ts"),
+      join(thisDir, "src", "webview/webview.tsx"),
+      join(thisDir, "src", "webview/editor.tsx"),
+    ],
+    platform: "browser",
+    outdir: join(thisDir, "out", "web"),
    plugins: [inlineStateComputeWorkerPlugin, buildPlugin],


build:watch outputs to out/web, but the extension manifest now points to out/browser/extension.js for the web entrypoint. This makes watch mode produce artifacts that VS Code won’t load. Align the watch outdir with the runtime entrypoints (e.g. out/browser and/or out/webview), or update the manifest/dev workflow accordingly.

minestarks · 2026-04-09T20:11:22Z

source/vscode/build.mjs

  if (isWatch) {
    watchVsCode();
  } else {
+    buildUI();


I find it kind of convoluted the way multiple parameters (platform, onlyUI) are plumbed through multiple layers of function, only to arrive at some hardcoded build configuration objects anyway.

At the end of the day we're just calling esbuild.build 4 times in a row with different configs, right? Couldn't we just define those configs inline here, and call buildBundle() directly?

Or you could put the 4 distinct configs in an array at the top of the file, and call buildBundle in a loop. This way they'd also be right next to commonBuildOptions -- they're kind of hard to find buried in the middle of the file, so it's hard to tell how the different options combine.

minestarks · 2026-04-09T20:11:45Z

source/vscode/build.mjs

 /** @type {import("esbuild").BuildOptions} */
-const buildOptions = {
+const commonBuildOptions = {
  entryPoints: [


entrypoints is always overwritten, should it be defined in commonBuildOptions at all?

minestarks · 2026-04-09T20:15:27Z

source/vscode/build.mjs

+ * Copy external node dependencies into node_modules/ under the extension
+ * directory so they can be resolved at runtime (e.g. when installed as a VSIX).
+ */
+function copyNodeExternals() {


This is a bit weird. If web-worker is a dependency we should just declare it as a dependency in package.json so it can be properly installed into node_modules by the package manager.

That said, I don't know why we can't bundle web-worker for node, the same way we do for the browser?

joao-boechat added 14 commits March 24, 2026 15:43

save initial progress

7fbc222

unify common exports in single file

2050f1a

first complete working version

adf2adf

remove redundant code from main.ts entrypoint

c482e3e

fix deprecated parameters

600f6ab

fix qsharp-lang tests

a074ed3

make generate_docs depend on web version of wasm

1db22da

use web-worker npm package to make worker code agnostic of platform (…

65adfc7

…browser vs node)

update vscode extension to match new worker api

642a244

update playground to match new worker api

59663b7

build node-workers separately, keep web-worker external for the node …

d1d3082

…environment

fix qsharp-lang tests

cb2566d

log platform, UI, and remoteName during extension activation

bf2bcf8

centralize platform env

dbff9f7

joao-boechat commented Apr 8, 2026

View reviewed changes

build.py Show resolved Hide resolved

joao-boechat added 2 commits April 8, 2026 11:41

export messageHandler for backwards compatibility

d4aa75a

update comments and README for qsharp-lang package

1de5b89

joao-boechat marked this pull request as ready for review April 8, 2026 19:45

joao-boechat requested review from ScottCarda-MS, billti, idavis, minestarks and swernli as code owners April 8, 2026 19:45

joao-boechat changed the title ~~enable the extension to run in node~~ Enable running the VS Code extension host on the workspace (Node.js) by default Apr 8, 2026

wasm-bindgen only builds to web

77a4efd

minestarks reviewed Apr 9, 2026

View reviewed changes

joao-boechat requested a review from Copilot April 9, 2026 19:54

Copilot started reviewing on behalf of joao-boechat April 9, 2026 19:55 View session

Copilot AI reviewed Apr 9, 2026

View reviewed changes

minestarks reviewed Apr 9, 2026

View reviewed changes

	declare const __PLATFORM__: string;
	declare const __PLATFORM__: "browser" \| "node";

		const wasmRequst = await fetch(uriOrBuffer);
		const wasmBuffer = await wasmRequst.arrayBuffer();

Conversation

joao-boechat commented Apr 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation

Architecture (of qsharp-lang)

Before

After

Changes

qsharp-lang npm package (source/npm/qsharp/)

VS Code extension (source/vscode/)

Build system (build.py)

Tests (source/npm/qsharp/test/)

Extra

Uh oh!

Uh oh!

ScottCarda-MS commented Apr 8, 2026

Uh oh!

joao-boechat commented Apr 8, 2026

Uh oh!

minestarks Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

joao-boechat Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

minestarks Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

minestarks Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

minestarks Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

minestarks Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

minestarks Apr 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

joao-boechat commented Apr 3, 2026 •

edited

Loading

`qsharp-lang` npm package (`source/npm/qsharp/`)

VS Code extension (`source/vscode/`)

Build system (`build.py`)

Tests (`source/npm/qsharp/test/`)

minestarks Apr 9, 2026 •

edited

Loading